Back to Contents        Previous        Next








3. User

PROCuser_error
A general function providing a convenient location for application-specific ‘good housekeeping’ actions which may be desirable when a ‘fatal’ error occurs. This procedure might typically be used to close any open files, unset system variables, etc.
It is called only when the global error trap is brought into play - see Section 2.8

PROCuser_initialise
A general function providing a convenient location for initialisation actions. This procedure should typically contain the following:
Window and menu loading/definition; declaration of global variables;
DIMming of arrays & data blocks; anything that needs to be done before polling starts.

FNuser_quit(type%)
Called when the application is being asked to quit, either due to the user choosing to quit the application or because of a desktop shutdown.
If type%=0 then it is an ‘application quit’.
If type%=1 then it is a ‘shutdown’.
Return a 1 to continue with the quit/shutdown or return a 0 to stop it e.g. to allow the user to save any data.
(See Section 2.27 of Manual for details.)

PROCuser_redraw(window%,minx%,miny%,maxx%,maxy%,printing%,p-age%)
When this function is called, the Wimp wants you to update/redraw the specified box (at least).
The box is in the window whose handle is window% or, if printing, then it is in paper coordinates with the origin is at the bottom left of the paper.
printing% = TRUE if currently printing, FALSE otherwise.
page% = number of page currently being printed if printing%=TRUE.
minx%,miny% = bottom left co-ordinates of box in screen/paper coordinates.
maxx%,maxy% = top right co-ordinates of box in screen/paper coordinates.

FNuser_menu(window%,icon%,screenx%,screeny%)
Responds to <menu> clicks. If you want a menu to be displayed when you press <menu> over a specified window/icon or particular mouse pointer position, then this function needs to return the handle of the menu required. Otherwise return 0.
window% = handle of window.
icon% = number of icon.
screenx%, screeny% give the mouse pointer position in screen OS units.
(<select> and <adjust> clicks handled by PROCuser_mouseclick)

PROCuser_mouseclick(window%,icon%,button%,workx%,worky%)
If <select> or <adjust> has been clicked in one of your windows then this function is called. (<menu> clicks handled by FNuser_menu)
window% = handle of window clicked over.
icon% = number of the icon clicked on (or -1 if no icon).
button% = which mouse button was pressed.
Eg. 4 for <select>, 1 for <adjust>.
workx%,worky% = work area coordinates of pointer (in window%)
when the mouse button was clicked.

PROCuser_openwindow(window%,x%,y%,stack%)
If this function is called, then the window whose handle is window% has been opened with the top left of the window at x%,y% on the screen.
stack% = window handle which window% was opened behind,
or -1 for top of window stack, or -2 for bottom.

FNuser_preclosewindow(window%)
This function is called just before the window whose handle is window% is about to be closed.
Return a 1 (default value) to allow the closing action to continue, or return 0 to stop the window closing.

PROCuser_closewindow(window%)
If this function is called, then the window whose handle is window%
has just been closed.

FNuser_keypress(window%,icon%,key%)
If a key is pressed while one of your windows has the input focus, or a hotkey is pressed, then this function is called (provided icon validation string is suitably defined).
If you don’t use the key press then return a 0. If you do then return a 1.
window% = handle of window with input focus.
icon% = number of icon with caret.
key% = key code. For most keys it is the ASCII number.
(See Section 2.4 of the Manual for codes of special keys - and Section 2.28 for validation strings.)

PROCuser_menuselection(menu%,item%,font$)
This function is called when the user has chosen a menu item from a menu/sub-menu.
menu% = handle of menu/sub-menu. (Will be the font menu handle if selection is from a font menu/font sub-menu.)
item% = item number (top item is 1). (Will be 0 if selection is from a font menu.)
font$=full period-separated font name. (Will be null string except if selection is from a font menu.)


FNuser_savefiletype(window%)
Used to identify Save windows. If the window is a Save window then you return the required filetype (as hex string. eg. ‘FFF’ for a textfile). Otherwise return a null string.
window% = handle of window%

PROCuser_saveicon(window%,RETURN drag%,RETURN write%,RETURN ok%)
This function allows the three save window icons (the one to drag, the writable icon for the filename/pathname and the OK button) to have
their icon numbers set, if you want to override the defaults.
Defaults:
drag% - 0 write% - 1 ok% - 2
window% = handle of save window.

FNuser_savedata(path$,window%)
Used to save/export data from an application.
Return a 1 if some data was saved, 2 if an error occurred or return a
0 for no data saved and no error.
path$ = full pathname of file to save data to i.e. destination file.
(Note that this must be a complete file path, not a directory.
Leafname is usually in save window writable icon.)
window% = handle of save window that file icon was dragged from.


FNuser_help(window%,icon%)
Used to return a string for interactive help when the mouse pointer is over the specified window and icon. Otherwise return a null string.
window% = handle of window (containing icon).
icon% = number of icon.
Note: the maximum allowable length of the returned string is 235 characters.

FNuser_menuhelp(menu%,item%)
Used to return a string for interactive help when the mouse pointer is over the specified menu and item. Otherwise return a null string.
menu% = handle of menu.
item% = number of item (starting from 1 at the top).
Note: the maximum allowable length of the returned string is 235 characters.


PROCuser_enteringwindow(window%)
This function is called when the pointer enters a window.
window% = handle of window.


PROCuser_leavingwindow(window%)
This function is called when the pointer leaves a window.
window% = handle of window.

FNuser_pane(window%)
If the window has a pane attached to it, then this function should
return the window handle of the pane. If the window doesn’t have a
pane attached, then it should return -1.
window% = handle of window.
(See Section 2.6 for use with multiple panes.)


FNuser_loaddata(path$,window%,icon%,filetype$,workx%,worky%)
Used to load data into application. Important to return a 1 if data is loaded.
path$ = full pathname of source file offered for loading.
window% = handle of window file has been dragged to. (Will be 0 if file double-clicked rather than dragged.)
icon% = number of icon file was dragged on to. (Will be -1 if file double-clicked rather than dragged.)
filetype$ = filetype of file offered for loading. Will always be at least three characters e.g. “FFF” or “0AF” (or ”1000” if a directory, or “2000” if an application)
workx%, worky% = work area coordinates the icon was dropped at (these values are both -1 if file was loaded with a double-click rather than dragged).

PROCuser_null
This is called continuously if you set NULL%=TRUE.
So, if you are writing something like a clock, you would monitor the time here and change any windows as required.

PROCuser_menuopen(menu%,window%,icon%)
Called just before menu (not a sub-menu) is opened.
menu% = handle of menu just about to open.
window%=window which pointer is over (or -1 if not over a window).
icon% = icon which pointer is over (or -1 if not over an icon).

PROCuser_overmenuarrow(rootmenu%,rootmenuitem%,RETURN nextsubmenu%,nextsubmenunumber%,parentmenuitem%,x%,y%)
Called when pointer moves over arrow-head against a menu item,
on the way to opening a sub-menu.
rootmenu%=handle of root menu of current menu tree.
rootmenuitem%=currently selected menu item in root menu.
nextsubmenu% = handle of submenu (or could be window) about
to be opened.
(Note: RETURN means that submenu handle can be changed here, if required.)
nextsubmenunumber%=position of next sub-menu in tree i.e. first sub-menu is 1, second sub-menu is 2, etc.
parentmenuitem% = menu item number which pointer is currently moving over. (Will be same as rootmenuitem%
for first sub-menu.)
x%/y% are screen OS-unit positions of pointer when over
arrow-head.

PROCuser_modechange
Called when the mode is about to be changed, but prior to the change taking place.
On mode change all open windows are re-opened, so this function is used only to set flags - which are then typically responded to in PROCwimp_openwindow().


FNuser_slider(window%,icon%)
In order to let DrWimp know that an icon is part of a slider/slider­back pair, return the slider icon number. Otherwise return -1.
window% = handle of window with slider pair in.
icon% = icon number of slider back icon.
(Always used with FNuser_sliderback as a complementary pair.)


FNuser_sliderback(window%,icon%)
In order to let DrWimp know that an icon is part of a slider/slider­back pair, return the slider-back icon number. Otherwise return -1.
window% = handle of window with slider pair in.
icon% = icon number of slider.
(Always used with FNuser_slider as a complementary pair.)



PROCuser_slidervalue(window%,slider%,pcent%,direction%)
When a slider is being dragged or has just finished being dragged, the percentage of the slider is passed to this function.
window% = handle of window with slider in.
icon% = icon number of slider.
pcent% = percentage of slider.
direction% = direction of slider (0 is horizontal, 1 is vertical)


PROCuser_declarefonts
Any fonts being used in printing must be declared in this function using PROCwimp_declarefont, PROCwimp_declarefonth and/or PROCwimp_declaredfilefonts.
(This is in case the application is used with a PostScript type
printer, which requires font declarations.)


PROCuser_print(minx%,miny%,maxx%,maxy%,page%)
Called to draw a page for printing, if PROCwimp_print was
called with user%=1.
minx%,miny% = coordinates of bottom left corner of clipping rectangle
on page in paper coordinates.
maxx%,maxy% = coordinates of top right corner of clipping rectangle on page in paper coordinates.
page% = number of page to print.

FNuser_printing(copy%,page%,totpages%,pagepos%)
Called repeatedly by DrWimp during printing so application can keep user informed of current printing status and give the option to cancel printing.
copy% = number of current copy being printed.
page% = number of current page being printed.
totpages% = total number of pages being printed.
pagepos% = current page being printed (starts at 1 each time and goes up to totpages%).
Return a 1 to cancel printing or a 0 to continue.


PROCuser_printerchange
Called when the printer settings or the current printer has changed so you can update your page measurements, current printer name, etc.

PROCuser_colourpickerrgb(red%,green%,blue%,none%)
When the colour picker window is used to select a colour (by pressing ‘OK’ or ‘None’) the ‘rgb’ values of the currently displayed colour are passed to this function. Requires RISCOS Version 3.50 or higher.
red% = red component of colour, in range 0-255.
green% = green component of colour, in range 0-255.
blue% = blue component of colour, in range 0-255.
If none%=0, OK was pressed in colour picker window i.e. displayed colour was selected.
If none%=1, ‘None’ was pressed in colour picker window i.e. no colour selection was made.
(Note: Colour values are still passed when ‘None’ is pressed.)


PROCuser_colourpickermodel(model%,value1,value2,value3,value4,non-e%)
When the colour picker window is used to select a colour (by pressing ‘OK’ or ‘None’) the ‘colour model’ values of the currently displayed colour are passed to this function. Requires RISCOS Version 3.50 or higher.
model%=’colour model’ number. 0 is ‘RGB model’, 1 is ‘CMYK model’, 2 is ‘HSV model’.
value1, value2 etc. are colour component values appropriate to the ‘model’, in range 0-100% (except value1 is in range 0-359 degrees for ‘HSV model’ i.e. when model%=2)
Note that value4 is only relevant for ‘CMYK model’ i.e. when model%=1. In other cases value4 will be -1.
If none%=0, OK was pressed in colour picker window i.e. displayed colour was selected.
If none%=1, ‘None’ was pressed in colour picker window i.e. no colour selection was made.
(Note: Colour values are still passed when ‘None’ is pressed.)


PROCuser_wimpmessage(messagenumber%,block%,reasoncode%)
Dr Wimp does not use all wimp-messages. This user-function allows details of those unused wimp-messages to be passed to the !RunImage, if required.
If the global variable
UNUSED% is set to TRUE then this user-function will be called whenever a wimp-message is received by the application but is not used within the DrWimp library. (UNUSED% is set to FALSE by default on application start-up.)
messagenumber% = number of the unused wimp-message received.
block%= handle of wimp-message data block, to enable user to get further information and respond if necessary.
reasoncode%= reason code passed by wimp (17, 18 or 19 in this case).
(See Section 2.30 of Manual for the list of wimp-messages that are currently used within the DrWimp library - and hence would never be passed on via this user-function.)


PROCuser_iconise(window%,RETURN text$,RETURN spritename$)
This function is called when ‘iconising’ action takes place. It allows the text and/or sprite used to be customised.
window% = handle of the window where the iconising action has occurred.
text$ = text to appear beneath the iconised sprite.
spritename$ = name of the sprite to be used, without the “ic_” prefix. A sprite with the full name needs to be supplied in the !Sprites/!Sprites22 files - otherwise the Wimp’s default sprite will be displayed.
(By default, spritename$ will be set to the application name as declared in FNwimp_initialise and text$ will be set to the title of the window being iconised. But if there is no title or the title includes the word “untitled” then the application name will be used as default.)
N.B. If spritename$ exceeds 7 characters it will produce an invalid iconiser sprite name - and hence the Wimp’s default iconiser sprite will be displayed instead.



FNuser_dragicon(window%,icon%,button%)
Used to specify which (draggable) icons are to be dragged and/or the circumstances under which they can be dragged. (See Section 2.25)
Return 1 when dragging of icon required, otherwise return 0.
window% = handle of window containing icon.
icon% = icon number of (draggable) icon.
button% = button being used for dragging i.e. 4 for <select-drag> or 1 for <adjust-drag>
(Note: This user-function will only be activated by icons which have a button type which is ‘draggable’.)



PROCuser_seticondragbounds(startwindow%,dragicon%,dragbutton%,-startmousex%,startmousey%,RETURN boundsminx%,RETURN boundsminy%,RETURN boundsmaxx%,RETURN boundsmaxy%)
This function is called when a draggable icon (or user-defined drag-box) is about to be dragged. It allows the drag boundaries to be set.
(If this user-function is left empty, the drag boundaries will be set automatically to confine the dragged icon to the visible window that it starts in.)
startwindow% - handle of window in which the dragged icon (or user-defined drag-box) starts.
dragicon% - handle of dragged icon. (Will be -1 when used with user-defined drag-box)
dragbutton% - button being used for dragging i.e. 4 for <select-drag> or 1 for <adjust-drag>
startmousex%, startmousey% - screen OS coords of mouse pointer at start of drag.
boundsminx%, boundsminy%, boundsmaxx%, boundsmaxy% - screen OS coords of rectangle within which icon (or user-defined drag-box) can be dragged.
(Default values are limits of visible window in which drag starts - see above.)



PROCuser_draggingicon(startwindow%,dragicon%,dragbutton%,startm-ousex%,startmousey%,mousex%,mousey%,overwindow%,overicon%,dr-agboxminx%,dragboxminy%,dragboxmaxx%,dragboxmaxy%)
This function is called repeatedly whilst an icon (or user-defined drag-box) is being dragged.
startwindow% - handle of window in which the dragged icon (or user-defined drag-box) starts.
dragicon% - handle of dragged icon. (Will be -1 when used with user-defined drag-box)
dragbutton% - button being used for dragging i.e. 4 for <select-drag> or 1 for <adjust-drag>
startmousex%, startmousey% - screen OS coords of mouse pointer at start of drag.
mousex%, mousey% - screen OS coords of instantaneous mouse pointer position during drag.
overwindow% - handle of window that is currently under pointer. (May be same as startwindow%. If currently not over a window, value will be -1)
overicon% - handle of icon that is currently under pointer. (If currently not over an icon, value will be -1)
dragboxminx%, dragboxminy%, dragboxmaxx%, dragboxmaxy% - instantaneous screen OS coords of ‘drag box’ rectangle.



PROCuser_endicondrag(startwindow%,dragicon%,dragbutton%,startm-ousex%,startmousey%,dragboxminx%,dragboxminy%,dragboxmaxx%,d-ragboxmaxy%,endwindow%,endicon%,endmousex%,endmousey%)
This function is called when the dragging of an icon (or user-defined drag-box) ends.
startwindow% - handle of window in which the dragged icon (or user-defined drag-box) starts.
dragicon% - handle of dragged icon. (Will be -1 when used with user-defined drag-box)
dragbutton% - button being used for dragging i.e. 4 for <select-drag> or 1 for <adjust-drag>
startmousex%, startmousey% - screen OS coords of mouse pointer at start of drag.
dragboxminx%, dragboxminy%, dragboxmaxx%, dragboxmaxy% - screen OS coords of ‘drag box’ rectangle in its end-of-drag position.
endwindow% - handle of window over which the dragging ends. (May be same as startwindow%. If not over a window, value will be -1)
endicon% - handle of icon over which the dragging ends. (If not over an icon, value will be -1).
endmousex%, endmousey% - screen OS coords of mouse pointer at end of drag.



PROCuser_definedragbox()
NOT IN SKELETON !RunImage.
ONLY USED AS PART OF ‘
Elixir_04’ for user-defined drag-boxes - see Manual Section 2.36 and 3.16.
Defines size/position of required drag-box. (Called only by PROCwimp_startuserdragbox().)


PROCuser_redrawtextline()
NOT IN SKELETON !RunImage.
ONLY USED AS PART OF ‘
Elixir_01’ for fast scrolling of long text lists - see Manual Section 2.36 and 3.16.
Needs to be used with
PROCwimp_calcredrawlines().

PROCuser_spritegraphics()
NOT IN SKELETON !RunImage.
ONLY USED AS PART OF ‘
Elixir_03’ for constructing a custom sprite - see Manual Section 2.36 and 3.16.





Top of page        Back to Contents        Previous        Next